docs: query cost limits for API tokens and roles - #695
Conversation
New page under AI agents documenting hourly/daily query spend limits, framed around giving AI agents a bounded query budget. Cross-linked from the AI agents overview, MCP server, tokens, and optimize-usage pages. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
📝 Vale prose report🟡 1 warning
Advisory only — this check never blocks the PR. ℹ️ How to read this & when it's fine to ignoreThis is advisory prose linting (Vale with the Google developer style guide). It is guidance, not a gate — nothing here blocks the merge. Fix the suggestions that improve the writing (contractions, first-person "we", terminology). It's expected that some won't make sense — ignore those. Vale reads Markdown as prose, so it sometimes flags code, identifiers, product/UI names, or example data that only look like prose. Those are false positives; leaving them is the right call. To silence a false positive at the source:
If a rule is consistently wrong for our docs, propose disabling it in |
'Spend limit' collides with the org-wide monthly spending limit in billing. 'Query cost limits' matches the console UI label and avoids both that collision and the plan-allowance 'query limit'. Adds disambiguation notes in both directions (new page <-> usage-billing). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
benenharrington
changed the title
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
| keywords: ["ai agents", "query cost limits", "budget", "mcp", "api tokens", "roles", "query usage", "429"] | ||
| --- | ||
|
|
||
| AI agents are heavy query users. An agent investigating an incident or exploring a dataset can run hundreds of queries in minutes, and unlike a human, it doesn’t pause to consider what the session costs. Query cost limits put a hard cap on that risk: you give a token or a role an hourly and a daily query budget in dollars, and Axiom blocks further queries for that identity when the budget is spent. The block lifts automatically when the window resets. |
There was a problem hiding this comment.
See this is in draft so forgive the early comment - noticed when linking gtm a preview for question from customer.
Just a thought... Let's not instil fear with "are heavy query users" and "it doesn’t pause to consider what the session costs".
"can be..." and "might not always be so thoughtful about..." etc can soften
…agents Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2 participants
Overview
Documents the new query cost limits feature: hourly and daily caps, in dollars, on the query costs of API tokens and roles.
Naming: the docs say “query cost limits”, matching the console UI labels in ctrl#8375 (“Query cost limits”, “Query cost limit reached”). “Spend limit” was avoided because it collides with the org-wide monthly spending limit in billing, and bare “query limit” collides with the plan’s monthly query allowance. The new page and the usage-billing page now disambiguate each other explicitly.
The canonical page is deliberately located in the AI agents group (
/console/intelligence/query-cost-limits, sidebar: Query cost limits) rather than in settings reference. The customer this feature is for is the heavy MCP/agent user, and the pitch the page leads with is theirs: give an agent a capped token and you know your worst-case query bill in advance, so you can let it run loose. Reference readers still find it through cross-links.Changes
console/intelligence/query-cost-limits.mdx— agent-first framing, then the mechanics: what counts as query cost (billed query GB-hours), fixed UTC hourly/daily windows,$0blocks all queries, 429 +Retry-Afteron trip, token vs role limits (role limits cover console, PATs, and OAuth sessions such as remote MCP; strictest limit across roles wins), usage meters, and what happens at/after the limit.docs.jsonbetween MCP server and Agent-created orgs.Claims are sourced from the merged backend work (axiom repo:
token-limitsandadd-user-limitsseries,pkg/edge/clients/limiter,pkg/core/common/querylimits) and the console PR (ctrl#8375): UTC clock-aligned windows, cents wire format/dollar UI, Axiom Cloud + Enterprise gate, per-scope 429s, and the “Query cost limits” / “Query usage” UI labels.Draft until
fe-query-cost-limits-2026-07flag is enabled — UI steps reference surfaces that aren’t live yet.Testing
pnpm audit:content: no unresolved links, floors pass.pnpm build: clean.🤖 Generated with Claude Code